SGI Developer Toolbox 6.1

home *** CD-ROM | disk | FTP | other *** search

/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 4.iso / src / apps / gmemusage / gmemusage.man < prev next >

Wrap

Text File | 1994-08-02 | 16.5 KB | 360 lines

GMEMUSAGE(1) UNIX System V GMEMUSAGE(1) NAME gmemusage - graphical memory usage viewer SYNOPSIS gmemusage [ -i interval ] [ -m | -p | -r | -s ] [ -u ] [ -a aiff-file ] [ -g growth-threshhold ] [ -t thresh ] [ -d delta ] [ progs ... ] DESCRIPTION gmemusage is a graphical memory usage viewer. gmemusage displays a bar chart depicting the breakdown of memory use, with each bar labeled with the name of the program using the memory and the number of kilobytes of memory used. If more than one copy of a program is running, the number of copies is displayed in parentheses after the program name. In addition, gmemusage will display a breakdown of the regions within a program. Clicking on a bar or program name in the main chart will replace the main chart with a chart for that program, with each region labeled with one of Text, Data, Break, Stack, Shmem, Physical Device, RW, RO, and (if possible) the base name of the file or device corresponding to each region. If gmemusage is unable to determine the base name of the file or device for a region that does correspond to a file or device, gmemusage will display the inode number of the file or device. The meanings of these labels are as follows: Text This region contains executable instructions. These instructions most likely came from an executable program file or a dynamic shared object. Data This region contains program data. Regions marked Data are usually associated with a particular executable program file or a dynamic shared object. Break Data region that is grown with brk(2). This is the region that contains memory allocated by malloc(3C). Stack Runtime stack. This is region is used for procecure call frames, and can grow if the program makes deeply nested procedure calls or calls procedures that allocate large amounts of stack space for temporary variables. Shmem A System V shared memory region. Page 1 (printed 6/30/94) GMEMUSAGE(1) UNIX System V GMEMUSAGE(1) Physical Device Region corresponds to a physical device other than main memory, such as a graphics device. RW Read/Write data without the Copy on Write bit set. This did not come from an executable program file or a dynamic shared object, and could be a memory mapped file. RO Read only data. U area & PTEs The user area and page table entries. This is information that the kernel uses to administer a process. Clicking on the Irix bar in Physical Memory Breakdown mode (see below) causes gmemusage to display a breakdown of the memory that it is charging to the operating system. Separate items include FS Cache, Buffer Data, Heap, Streams, Zone, BSD Networking, Page Frame Data, Kernel Tables, Unix Data Space, Unix Code Space, Symmon, and Other. When viewing the breakdown of program memory usage, clicking and dragging on the shadow bar will switch the display to another program. The first time a program is clicked on, gmemusage reads in information about executables and libraries on the system while displaying a wait message. gmemusage keeps this information in its database file $HOME/.gmemusage.inodes. if this file does not exist or is older than /unix, gmemusage will create it, which can take as long as a minute. If the database already exists and is newer than /unix, reading it will only take a few seconds. See ENVIRONMENT VARIABLES below for information on customizing $HOME/.gmemusage.inodes. gmemusage has four different modes of viewing. The default mode, Physical Memory Breakdown, shows the amount of physical memory being used by each process, the amount of free memory, and the amount of memory being used by Irix. The amount of memory charged to each process is calculated by taking the pages each process has in memory and pro- rating the sizes with the number of processes using each page. The mode Total Sizes of Process shows the the total sizes of all the processes in the system. This corresponds to the SZ field of ps(1) output. The mode Resident Sizes of Processes shows the resident Page 2 (printed 6/30/94) GMEMUSAGE(1) UNIX System V GMEMUSAGE(1) sizes of all the processes in the system. This corresponds to the RSS field of ps(1) output. The mode Resident Mappings shows the resident sizes of all mapped objects in the system. A mapped object can correspond to an executable file, a dynamic shared object, a memory mapped file, or a region attached to a process by rld(1). By default, gmemusage only displays programs that are using more than 500 kilobytes of memory; programs using less than this are lumped together and labeled < 500. This threshhold is specifiable on the command line and changeable at run time. Alternatively, a list of programs to monitor can be specified on the command line (see below). In this case, a bar for each of the programs specified appears (as long as that program is running) and any threshhold is ignored. In addition to the four basic viewing modes and the process region breakdown, gmemusage cycles through displays of additional information when the 'v' key is pressed. This additional information is a subdivision of each bar in the chart, with the right portion of each bar corresponding to the additional information. Down the right side of the window the values corresponding to the right portion of each bar are displayed. The following additional information is available: Private The portion of each bar that is private memory; that is, memory which is not being shared. This additional information is available in all modes, except when viewing the Irix breakdown. Shared The portion of each bar that is shared between more than one process. This is calculated by subtracting the Private amount from the Physical amount for each bar. Shared is available in all modes, except when viewing the Irix breakdown. Physical The portion of each bar that is consuming physical memory. Physical is available in Resident Sizes of Processes and and Total Sizes of Processes modes. Resident The portion of each bar that is resident in memory (without taking sharing into acount). Resident is available in Total Sizes of Processes mode. If the environment variable USAGESOUND is set to a valid Page 3 (printed 6/30/94) GMEMUSAGE(1) UNIX System V GMEMUSAGE(1) aiff file, and playaiff(1) is installed, gmemusage will use playaiff(1) to play $USAGESOUND when viewing a program's region breakdown and the program grows by a threshholded amount. The command line option -a can be used as an alternative to the environment for specifying a sound file, and the growth threshhold can be specified on the command line (see below). gmemusage has the following command line options: -iinterval Update display every interval milliseconds. The default in the absence of the -i option is 500. -m Start using Resident Mappings mode. -p Start using Physical Memory Breakdown mode. This is the default. -r Start using Resident Sizes of Processes mode. -s Start using Total Sizes of Processes mode. -u Rebuild the inode database $HOME/.gmemusage.inodes even if it isn't older than /unix (see FILES below). -tthresh Use thresh kilobytes instead of 500 kilobytes as the starting threshhold. Programs using less than this amount of memory in a particular view are not displayed separately, but rather are lumped together in a single bar. -ddelta Change the threshhold by delta kilobytes when the up and down arrow keys are pressed (see below). The default is to change the threshhold by 50 kilobytes. -aaiff-file Specify an aiff sound file to be played when viewing a program's region breakdown and the program grows by more than a threshhold amount (see -g option). -ggrowth-threshhold Specify in kilobytes the growth threshhold. This is the amount a program has to grow before gmemusage will play a sound. The default is 12. progs Any command line arguments following the arguments described above are interpreted as names of programs. If program names are specified, Page 4 (printed 6/30/94) GMEMUSAGE(1) UNIX System V GMEMUSAGE(1) gmemusage only displays the memory usage of the programs specified, with all other programs lumped together in a bar labeled Other. In this case, any threshhold or delta is ignored. This is useful when one is interested in the behavior of a particular program or set of programs, such as when testing for memory leaks. Runtime controls Some of gmemusage's display parameters can be modified at runtime. Pressing the 'p' key selects Physical Memory Breakdown mode. Pressing the 'r' key selects Resident Sizes of Processes mode. Pressing the 's' key selects Total Sizes of Processes mode. Pressing the 'v' key cycles through the available additional information for the current mode (see above discussion of additional information). The up arrow key increases the threshhold by 50 kilobytes (default) or, if the -d option was specified, by delta kilobytes. The down arrow key decreases the threshhold by the same amount. When the threshhold is decreased to 0, all progams running are displayed, even those that use no memory (such as kernel processes). In the main view, clicking on a program's bar causes gmemusage to display a detailed memory usage chart for that program. In the detailed usage view, clicking on the shadow bar switches the program being displayed, and clicking outside the shadow bar or pressing the space bar returns to the main view. At any time, pressing the 't' key causes gmemusage to print statistics about the current view to the terminal window. The fields in each line are separated by tab characters to simplify the parsing of the output by other programs (they are also padded with spaces). There are three different types of print outs: All Programs, Resident Mappings, and program breakdown. Which gets printed depends on the mode gmemusage is in when 't' is pressed. The 'h' key brings up an on-line help screen, and the space bar returns from there to viewing memory. The escape key exits. EXAMPLES gmemusage -p -t 1000 -d 100 Bring up gmemusage in Physical Memory Breakdown mode, with programs using 1000 kilobytes or more of memory displayed separately in their own bars. The up and down arrow keys Page 5 (printed 6/30/94) GMEMUSAGE(1) UNIX System V GMEMUSAGE(1) will increase and decrease the threshhold by 100 kilobytes respectively. gmemusage -r xwsh toolchest 4Dwm Xsgi fm Bring up gmemusage in Resident Sizes of Processes mode. Display bars for xwsh(1), toolchest(1), 4Dwm(1), Xsgi(1), and fm(1). All other programs will be combined into a bar labeled Other. FILES $HOME/.gmemusage.inodes Table of files that are likely to correspond to regions mapped into processes, along with inode numbers. gmemusage builds this table if it doesn't exist or if it is older than /unix or if the -u option is supplied, and uses it to label the bars when viewing memory breakdown within a process. See ENVIRONMENT VARIABLES below for information on altering how $HOME/.gmemusage.inodes is built. /proc gmemusage gets memory usage information for processes from the /proc file system. ENVIRONMENT VARIABLES USAGESOUND If set, $USAGESOUND is used as an aiff file to be played by playaiff(1) when viewing a process's region breakdown and the process grows (see above). USAGEPATH Colon separated list of directories to recursively search when building the inode database, $HOME/.gmemusage.inodes. If USAGEPATH is not found in the environment, gmemusage uses the following default path: /usr/ToolTalk:/usr/bin:/usr/lib:/usr/local:/usr/Cadmin: /usr/CaseVision:/usr/sbin:/usr/bsd:/usr/etc:/lib:/sbin: /bin:/etc:/usr/gfx BUGS The totals displayed for the breakdown of a program's regions do not always add up exactly to the amount of memory in the main view. In Physical Memory mode, this discrepancy is due to rounding error. In Total Size mode, this is often due to the inclusion of physical devices in the breakdown. The Resident Size discrepancies are currently being studied. Page 6 (printed 6/30/94) GMEMUSAGE(1) UNIX System V GMEMUSAGE(1) Beware of "shared object amortization". When a program that uses a shared object (e.g. libXm.so) is started, the memory usage of all other programs that use that shared object can decrease. This is because the amount of memory charged to each program for shared object usage is prorated based on the amount of sharing. If you have problems, questions, or comments, please send mail to rogerc@sgi.com. SEE ALSO ps(1), top(1), gr_top, osview(1), gr_osview(1), proc(4). Page 7 (printed 6/30/94)